home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / m2 / m2_part1.lha / modula / dice / dice.LHA / doc / dcc.doc < prev    next >
Text File  |  1991-04-05  |  27KB  |  683 lines
  1.  
  2. dcc/dcc                                 dcc/dcc
  3.  
  4.                 DCC.DOC
  5.  
  6.                   Matthew Dillon
  7.                   891 Regal Rd.
  8.                   Berkeley, Ca. 94708
  9.                   USA
  10.  
  11.                   dillon@overload.Berkeley.CA.US        --or--
  12.                   uunet.uu.net!overload!dillon
  13.  
  14.                   BIX: mdillon
  15.  
  16.     DCC <options and files>
  17.  
  18.     NOTE:   new this version, use of single precision IEEE libraries for
  19.     floating point.   Please read the note under the option '-ffp' for
  20.     more information.
  21.  
  22.     DCC is similar to the UNIX 'cc' command and is the frontend for the
  23.     DICE compiler.  For best performance I strongly suggest that you make
  24.     DCC, DC1, DCPP, DAS, and DLINK resident.  If you do not have enough
  25.     memory to do so you at least want to leave the largest programs, DC1
  26.     and DAS resident.    It is suggested that your machine have at least 1MB
  27.     of memory.    A compile or link can take as much as 400K of run-time
  28.     memory.
  29.  
  30.     Options may occur anywhere on the command line but MUST occur singly.
  31.     That is, -c -a instead of -ca.  file arguments to options may occur
  32.     with or without an intervening space.  -oFILE and -o FILE are both legal.
  33.  
  34.     Files ending in .a[sm] are assumed to be assembly files.  Files ending
  35.     in .l[ib] are assumed to be library files.    Files ending in .o[bj] are
  36.     assumed to be object files.  All other files are assumed to be C source
  37.     files.
  38.  
  39.     Normally DCC compiles all C source files, assembles all .a[sm] files,
  40.     and links the resulting object files with any specified .o files
  41.     together to produce an executable.    The output file may optionally be
  42.     specified with the -o option.  If not specified, a default output
  43.     filename based on the name of the input file is generated.    This
  44.     general action is modified by two options:
  45.  
  46.     -c    DCC does NOT link, -o specifies the output object file
  47.  
  48.     -a    DCC does NOT assemble (i.e. leaves the .a file resulting from
  49.         a compile).  -o specifies the output assembly file
  50.  
  51.     If neither option is given -o specifies the name of the resulting
  52.     executable.
  53.  
  54.     The default object directory is T: and may be changed with the -O option.
  55.     The default temporary directory is also T: and may be changed with the -T
  56.     option.  IF YOU HAVE LIMITED MEMORY you may have to specify that
  57.     temporary files not be placed in T: either by re-assigning T: or using
  58.     the -T option.  DICE goes much slower if temporary files must be written
  59.     to a floppy or even a hard disk.
  60.  
  61.     WARNING: .a[sm] files are assembled with DAS, read DAS.DOC if you
  62.     intend to assemble non-DC1 generated assembly.
  63.  
  64.         ------------------- OPTIONS ------------------
  65.  
  66.     file    File to compile, assemble (.a), and/or link (.o, .lib)
  67.  
  68.     @file    File containing further list of files, one per line.
  69.         (blank lines and lines beginning with ';' or '#' are
  70.         ignored.  File may NOT contain further options).
  71.  
  72.     -E file    specify stderr file, any errors are appended to the file
  73.         instead of to stdout.  Useful for batch compiles
  74.  
  75.     -c        Compile C source files and assemble into OBJECT files
  76.         only (do not link).
  77.  
  78.     -a        Compile C source files into ASSEMBLY files (do not assemble
  79.         or link).
  80.  
  81.         Keep in mind the DAS will do further optimizations on the
  82.         assembly file that you see.
  83.  
  84.     -l0     Do not link default libraries (dlib:c.lib dlib:amigas.lib
  85.         dlib:auto.lib), or standard startup (dlib:c.o and
  86.         dlib:x.o).
  87.  
  88.         BEGINNER'S NOTE:    Do not use this option
  89.  
  90.         This option is used in special circumstances, such as when
  91.         generating .libraries or .devices.
  92.  
  93.         WARNING: DICE is much more dependant on its startup code
  94.         (c.o and x.o) than other compilers, do not link without
  95.         the startup unless you know what you are doing.
  96.  
  97.     -l lib    When linking include this library. (space is optional)
  98.  
  99.         Generally -l is used to include the math library (-lm)
  100.         when formatted floating point *printf()s are required.
  101.  
  102.     -2.0    Default amiga.lib is    dlib:amigas20.lib
  103.         Default amiga include path is dinclude:amiga20/
  104.  
  105.         -2.x where 'x' is the second digit replacing the '0' in the
  106.         above example.    This option is useful when compiling for
  107.         different versions of the operating system.
  108.  
  109.     -1.4    Like -2.0, but using dlib:amigas14.lib and dinclude:amiga14/
  110.  
  111.         Again, -1.x may be specified.
  112.  
  113.     -L0     remove default library search path, including all explicitly
  114.         specified (-L dir) directories up to this point.
  115.  
  116.     -L dir    add the specified directory to the library search path.  If
  117.         the object module or library can not be found in the
  118.         current directory, directories specified with -L are
  119.         searched.  -L directories are searched before the default
  120.         library directory (DLIB:), assuming it was not removed
  121.         with -L0 .
  122.  
  123.         Note that the directory path specified by -L is used to
  124.         search for libraries AND object modules.
  125.  
  126.         A trailing '/' is optional
  127.  
  128.     -I0     remove default include path from search list.  The default
  129.         include path is dinclude: and dinclude:amiga/ (unless
  130.         modified by -1.x and -2.x options)
  131.  
  132.     -I dir    When compiling scan this include directory (space is
  133.         optional) The specified path takes precedence over defaults
  134.         but defaults are NOT removed.
  135.  
  136.     -D define[=value]
  137.         Pre-define a symbol
  138.  
  139.     -U        undefine __STDC__, mc68000, _DCC, and AMIGA.
  140.  
  141.     BEGINNER'S NOTE:    Do not use any of these options
  142.  
  143.     -o file    Specify output executable, object, or assembly file name
  144.         depending on what you are producing.  The space is optional
  145.  
  146.     -020    generate code for the 68020 and later microprocessors
  147.     -030    generate code for the 68030 and later microprocessors
  148.     -881    generate inline FFP code for the 68881
  149.     -882    generate inline FFP code for the 68882
  150.  
  151.     BEGINNER'S NOTE:    Do not use any of these options
  152.  
  153.     These options exist to produce 020 and 030 opcodes, and 881/882
  154.     inline assembly for floating point operations.    They are not
  155.     necessarily implemented yet.  The intent is to implement them
  156.     by V2.06 .
  157.  
  158.     -md     small data model (default)      uses A4-relative
  159.     -mD     large data model        uses absolute-long
  160.     -mc     small code model (default)      uses PC-relative
  161.     -mC     large code model        uses absolute-long
  162.  
  163.     BEGINNER'S NOTE:    Use only -mD if you declare more than
  164.     64KBytes of data.
  165.  
  166.     These options specify the default data and code model to use.
  167.     The model may be overriden by use of the __near and __far
  168.     type qualifiers (see EXTENSIONS.DOC) on a variable by variable
  169.     basis.
  170.  
  171.     DICE defaults to the small data and small code model, and is able
  172.     to generate >32KBytes of code using the small code model so you
  173.     should never have to use -mC.  Note that the DICE libraries have
  174.     all been compiled with the small-data model, and certain
  175.     applications may disrupt the base register, A4... in this case
  176.     use of the __geta4 type qualifier should be of use.  If worse
  177.     comes to worse you can recompile a large-data model C.LIB, but
  178.     I suggest you try other solutions first.
  179.  
  180.     -ms0    (default), only const objects are put into a CODE hunk
  181.     -ms     string constants are put into the read-only code hunk
  182.     -mS     string constants are put into the read-only code hunk AND
  183.         all external const references use NEAR addressing
  184.     BEGINNER'S NOTE:    Use only -ms
  185.  
  186.     -ms0 turns off -ms/-mS in case you have it in your DCCOPTS enviroment
  187.     variable and want to turn it off.
  188.  
  189.     Default operation (no -ms or -mS) puts 'const' items into a
  190.     read-only CODE hunk.  Locally declared objects are referenced
  191.     using PC-REL while external objects (declared in some other
  192.     module) are referenced using 32-BIT ABSOLUTE addressing.
  193.  
  194.     -ms will additionally make all string constants, such as "fubar",
  195.     const and referenced via PC-REL.  -ms is an extremely useful
  196.     option when you will never modify any of your string constants
  197.     because the strings are not copied for multiple running instances
  198.     of the program (if resident).
  199.  
  200.     -mS works like -ms, but in addition forces all external const
  201.     references to use PC-REL addressing INSTEAD of 32-bit absolute
  202.     addressing.  THIS IS A VERY DANGEROUS OPTION, DO NOT USE UNLESS
  203.     THE FINAL CODE SIZE IS LESS THAN 32 KBytes.
  204.  
  205.     Using -ms along with -r can result in huge savings of memory due to
  206.     the string constants being moved out of the data segment (which
  207.     must be duplicated for each running instance of the program).
  208.  
  209.     WARNING WARNING.  In all cases if you declare an object as 'const'
  210.     it must be extern'd as 'const' in other modules or incorrect code
  211.     will be generated.  This is true whether you use -ms/S or not.
  212.  
  213.     -mr     registered arguments, light
  214.     -mR     registered arguments, medium
  215.     -mRR    registered arguments, strict
  216.  
  217.     BEGINNERS NOTE:     either do not use these options or use only -mr
  218.     BEGINNERS NOTE:     see REGARGS.DOC
  219.  
  220.     These options control the automatic registerization of procedure
  221.     arguments.  Only those prototyped procedures declaring 4 or fewer
  222.     arguments will be registered.  Values are passed in D0/D1/A0/A1
  223.     according to the type of variable and availabilty of registers/
  224.  
  225.     -mr generates entry points for both the registered argument and
  226.         normal version of the function.  This option is ideal for
  227.         generating multi-model libraries.
  228.  
  229.     -mR generates only a single, registered entry point
  230.  
  231.     -mRR is similar to -mR but extends registerization to indirect
  232.         function calls (that are fully prototyped).  This is the
  233.         most dangerous option.
  234.  
  235.     Note that -mr and -mR assign the normal, nonregistered entry point
  236.     of a function to any indirect function pointers whether they are
  237.     fully prototyped or not (e.g. void (*func)() or void (*func)(int) )
  238.  
  239.     -mRR assigns either the registered or normal entry point to
  240.     function pointers depending on whether they are prototyped or not
  241.     (and any calls made through these function pointers will use the
  242.     registered args method).
  243.  
  244.     WARNING:    -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE
  245.     CALL-BACK FUNCTIONS AS ARGUMENTS.  -mr and -mRR *CAN* be used,
  246.     however with -mRR you must be careful to supply the registered
  247.     entry point.
  248.  
  249.     WARNING:    AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS
  250.     ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS.  Thus if
  251.     you use -mRR you *must* qualify the procedure or function pointer
  252.     type specification with __stkargs to entire it has a normal
  253.     entry point.
  254.  
  255.     -mw <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  256.         AMIGA EXECUTABLES
  257.  
  258.     BEGINNER'S NOTE:    Do not use this option
  259.  
  260.     This option is another data model, called the ABSOLUTE-WORD data
  261.     model.    Source files compiled with this option generate
  262.     absolute-word data references to access data objects instead of
  263.     A4-relative or absolute-long.  The base of the data segment must be
  264.     specified as decimal, 0octal, or 0xHEX.
  265.  
  266.     Since absolute-word is used exclusive of A4-relative, the compiler
  267.     will now use A4 for register variables.  You may NOT mix -mw
  268.     modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC)
  269.  
  270.     The ROMABLE program is usually run on the executable generated by
  271.     DLink to generate a ROM.
  272.  
  273.     -ma <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  274.         AMIGA EXECUTABLES
  275.  
  276.     BEGINNER'S NOTE:    Do not use this option
  277.  
  278.     This option specifies to the compiler and linker that the resulting
  279.     code is intended to be relocated to a permanent data address, that
  280.     specified by <addr> in decimal, 0octal, of 0xHEX.
  281.  
  282.     Unlike -mw, -ma assumes that the data segment can be placed
  283.     anywhere.  The ROMABLE program is usually run on the executable
  284.     generated by DLink to generate a ROM.
  285.  
  286.     You may still specify a data model, -md or -mD, to use with this
  287.     option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  288.     may be mixed with the small-data model.  Again, see ROMABLE.DOC
  289.  
  290.     -rom    SET UP OPTIONS FOR GENERATING ROMABLE CODE
  291.  
  292.     BEGINNER'S NOTE:    Do not use this option
  293.  
  294.     Like -l0, -rom disables automatic inclusion of a startup file (you
  295.     must specify your own) and libraries.  However, x.o is still
  296.     included to sink any autoinit code.  Your startup code must handle
  297.     the appropriate model and call autoinit code before calling your
  298.     program main
  299.  
  300.     This option is used to support ROMed firmware, i.e. non-amiga
  301.     executables.  You should never link with C.LIB.  Instead, a new
  302.     library, ROM.LIB, is available.
  303.  
  304.     ROM.LIB contains no static or global references and thus works
  305.     with any data model, and only completely self-contained routines
  306.     are included.  The only data ROM.LIB uses is stack-based.  All
  307.     ROM.LIB routines are completely reentrant, including
  308.     [v]sprintf() !
  309.  
  310.     -proto    PROTOTYPE CHECKING AND OPTIMIZATIONS
  311.  
  312.     When this option is used, an ERROR message will be generated for
  313.     any call that is not prototyped.  This option is useful to ensure
  314.     that you have properly prototyped routines (when you use
  315.     prototypes), especially when floats and doubles are passed and
  316.     indirect function pointers are used (they must be prototyped as
  317.     well!).
  318.  
  319.     IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION.
  320.     Currently, chars and shorts are extended to long's when pushed onto
  321.     the stack for a subroutine call.  In the future if the -proto
  322.     option is used these objects will be pushed as shorts and not
  323.     extended.
  324.  
  325.     -r        Make executable residentable with separate CODE & DATA hunks
  326.     -pr     Make executable residentable w/ no relocation hunks
  327.     -pi     Make executable NON-residentable w/ no relocation hunks
  328.  
  329.     BEGINNER'S NOTE:    Just use -r to get residentable executables and
  330.     do not worry about these other options.
  331.  
  332.     -pr/-pi generate 'position independant' code also useful for ROMed
  333.     applications.  NOTE that -pi and -pr force const items to be
  334.     referenced pc-relative as well, causing -ms and -mS to do the same
  335.     thing (when combined with -pr/-pi)
  336.  
  337.     CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi
  338.  
  339.     Refer to the section below called 'RESIDENTABILITY' for a
  340.     discussion of these options
  341.  
  342.     NOTE ROPT1:    You may not make data references within const
  343.     declared objects when using the -r/-pr options.  This is because
  344.     the CODE hunk is shared between running instances of the program
  345.     and these address references would be different between the
  346.     instances.
  347.  
  348.     However, if you are using the -ms option, string constants will
  349.     be in the code section and thus no problem.
  350.  
  351.     -O outdir    Specify directory that is to contain output executable,
  352.         object, or assembly files (used when specifying multiple
  353.         source files)
  354.  
  355.     -O is useful to tell the compiler where to put the objects
  356.     when you use dcc to compile and link a whole bunch of files
  357.     at once.  In this case, the -o option can still be used to
  358.     specify where to put the final executable.
  359.  
  360.     NOTE:    The -O name is used as a prefix so if you are
  361.     specifying a directory be sure it has a ':' or '/' on
  362.     the end.
  363.  
  364.     -T tmpdir    Specify the temporary directory used to hold preprocessed
  365.         source files and temporary assembly files... files that
  366.         will be deleted after use.
  367.  
  368.     NOTE:    The -T name is used as a prefix so if you are
  369.     specifying a directory be sure it has a ':' or '/' on
  370.     the end.
  371.  
  372.     The default is T: .. this option is useful in low-memory situations
  373.     where you may decide to put intermediate files elsewhere.  Putting
  374.     intermediate files on your HD or floppy slows down compilation by
  375.     an order of magnitude, but if you are running on a system with
  376.     little memory you may not have a choice.
  377.  
  378.     -s        Include symbolic debugging information in the executable.
  379.         (dlink opion)
  380.  
  381.     This option includes the symbol table in the resulting executable
  382.     and is passed to dlink.  When using DOBJ to disassemble an
  383.     executable, DOBJ will use the symbol table to generate a more
  384.     symbolic dump.
  385.  
  386.     -S        ALTERNATE SECTION NAMING OP FOR LIBRARIES
  387.  
  388.     When making libraries: uses alternate section naming conventions so
  389.     that all initialized data in the module will be placed before any
  390.     initialized data in non -S modules (i.e. normal linked object
  391.     files).  Any library BSS will be placed before non-library BSS.
  392.     Thus, the final ordering in the final executable will be:
  393.  
  394.         [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS]
  395.  
  396.     Thus, if your program contains >64K Bytes of BSS you can still
  397.     link with a library that tries to reference its own BSS using
  398.     the small-data model.  If your library declares only initialized
  399.     data (i.e. int x = 0; ), then you can link with the library even
  400.     if your program declares >64KBytes of *initialized* data !
  401.  
  402.     -v        Display commands as DCC executes them.
  403.  
  404.     -new    Checks timestamps for source/destination and only
  405.         compiles/assembles if object is outdated or does not
  406.         exist.    Used to make DCC a standalone make.
  407.  
  408.     -f        FAST / ^C HANDLING FOR 1.3
  409.  
  410.         This option is used for 1.3 only.  You MUST be using the
  411.         commodore shell (NewShell) and if you make programs
  412.         resident you MUST use the commodore C:Resident command.
  413.  
  414.         This option will probably not work if you use WShell or
  415.         ARPShell under 1.3.  This option allows DICE to take
  416.         short cuts to run sub-programs and allows ^C to be
  417.         propogated to said programs.  This option is useful
  418.         to set permanently in your DCCOPTS ENV: variable if
  419.         you run under 1.3
  420.  
  421.         DICE under 2.0 has no such problems and will run sub
  422.         programs optimally, including propogation of ^C.
  423.  
  424.     -frag    FRAGment (linker option).
  425.  
  426.     Tell linker not to combine all code hunks together or combine all
  427.     data hunks together. Cannot be used if the -r or -mw options are
  428.     used. Generally only useful if the large-data model is used.  Not
  429.     entirely supported yet.
  430.  
  431.     -ffp    Set fp library for floats
  432.     BEGINNER'S NOTE:    When using single precision floating point
  433.     this option, use of the original ffp libraries, will make the
  434.     program portable across all amigas.  Otherwise only amigas that
  435.     have the commodore MathIeeeSing*.library libraries will be
  436.     able to run the program.
  437.  
  438.     If not specified, 'mathieeesingtrans.library' and
  439.     'mathieeesingbas.library' are used.  These are new 2.0 libraries
  440.     that may not exist on all machines yet.
  441.  
  442.     If specified, 'mathtrans.library' is used .. motorola's FFP float
  443.     library.
  444.  
  445.     NOTE:  IF -ffp is used, be warned that conversion from floats to
  446.     doubles and back again is not entirely reliable.
  447.  
  448.     -d#     Set debugging level (# = a number), used for compiler
  449.         diagnostics only.
  450.  
  451.     -d<opts>    Specify any combination of debugging options.  These options
  452.         may be combined in one -d option.
  453.  
  454.         Currently no options are defined.
  455.  
  456.     -gs     Generate Dynamic Stack Code.  This generates code on every
  457.         subroutine call to check available stack.  If available
  458.         stack falls below 2K a new stack frame is allocated which
  459.         will be deallocated when the subroutine returns.
  460.  
  461.         If the allocation fails, stack_abort() is called.  If this
  462.         routine is not defined by you, the library stack_abort()
  463.         will call abort().  REFER TO DOC/EXTENSIONS.DOC FOR
  464.         MORE INFO.cd src
  465.  
  466.  
  467.         This option is extremely useful when compiling UNIX code
  468.         that expects infinite stack.
  469.  
  470.     -chip    CHIP force (linker option).
  471.  
  472.     Tell linker to force all hunks into CHIP memory.  You should
  473.     generally not use this option.    Instead, use the __chip
  474.     keyword (see EXTENSIONS.DOC) for those specific data items
  475.     that need to be in CHIP memory.
  476.  
  477.     NOTE:    CHIP data items are accessed using the large-data
  478.     model, thus you cannot create residentable executables that
  479.     contain __chip declarations UNLESS THEY ARE ALSO 'const'
  480.     objects -- read-only.
  481.  
  482.     -aztec    The front end attempts to run Aztec executables
  483.     -lattice    The front end attempts to run Lattice executables
  484.     -sas    same as -lattice
  485.  
  486.     These options allow one to write a single DMakefile able to handle
  487.     compilation under any compiler, assuming the source is compilable
  488.     under any compiler.
  489.  
  490.     These are very limited options and may not work across new
  491.     versions of Aztec or Sas/C
  492.  
  493.  
  494.     The ENV:DCCOPTS enviroment variable may contain additional options.
  495.  
  496.     ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  497.     enviroment variable.  If you do not use ENV: then assign it to RAM:
  498.  
  499.  
  500.     Example #1.  Compile hello.c to executable.  The objects will be
  501.         left in T:
  502.  
  503.     1> dcc hello.c -o ram:hello
  504.     1> ram:hello
  505.  
  506.     Example #2.  Compile hello.c to executable and put the object file
  507.         in X:
  508.  
  509.     1> dcc hello.c -o ram:hello -TX:
  510.  
  511.     Example #3.  Compile hello.c into object into RAM: then link with symbols
  512.  
  513.     1> dcc -c hello.c -o ram:hello.o
  514.     1> dcc ram:hello.o -o ram:hello -s
  515.  
  516.     Example #4.  Compile foo.c and link with an already compiled object file
  517.          gar.o to produce an executable.  foo.o is placed in
  518.          T:
  519.  
  520.     1> dcc foo.c gar.o -o ram:foogar
  521.  
  522.                   PREPROCESSOR
  523.  
  524.     Predefined Symbols:
  525.  
  526.     __LINE__        current line number (integer constant)
  527.     __DATE__        current date (string)
  528.     __TIME__        current time (string)
  529.     __FILE__        current file (string)
  530.  
  531.     __BASE_FILE__        base source file (string), allows specification
  532.                 of the actual name of the source file from
  533.                 within an include file.
  534.  
  535.                 (-U undefines the below symbols)
  536.     __STDC__
  537.     mc68000
  538.     _DCC
  539.     AMIGA
  540.     _FFP_FLOAT        set if single prec. floats are in FFP format
  541.     _SP_FLOAT        set if single prec. floats are in IEEE-SING format
  542.                 (default)
  543.  
  544.     NOTE:  There are no limits to symbol and macro lengths.
  545.  
  546.                        MODELS
  547.  
  548.     DICE defaults to using the small-code and small-data models.  You can use
  549.     the small-code model even if your code is larger than 64K.    However, to
  550.     accomplish this DLINK uses one or more JUMP tables, and thus doing direct
  551.     comparisons of the address of a given procedure may yield a different
  552.     address depending on the module.  If this is a problem you must either
  553.     change the code or use the large-code model.
  554.  
  555.     The small-data model uses 16 bit A4-relative references to access
  556.     static and global data.  This has the advantage of making the executable
  557.     smaller for two reasons:
  558.  
  559.     (1) each reference requires only one word of extension instead of two.
  560.  
  561.     (2) The linker is able to completely resolve the relative offsets
  562.         and thus no relocation information is required in the final
  563.         executable for such references.
  564.  
  565.     The small-data model also makes code run a bit faster.  When you compile
  566.     with the large-data model, note that the library code (C.LIB) still uses
  567.     small-data references to access library based globals.  This is
  568.     normally not a problem since, due to the ordering of sections in the
  569.     startup module, all library data occurs before user data and is thus
  570.     within the A4 relative range.  However, there is one problem that you
  571.     might come up against... since BSS is always placed after initialized
  572.     DATA, if you have more than 64KBytes of initialized data the linker may
  573.     give up with an error due to library BSS being beyond the A4 relative
  574.     offset range.
  575.  
  576.                PUTTING CONST DATA INTO THE CODE SEGMENT
  577.  
  578.     Two options are available to handle the 'const' keyword: -ms and -mS.  If
  579.     neither are used 'const' is ignored.  The difference between the two
  580.     determines how external references (between modules) are handled.
  581.  
  582.     With -ms, all string constants "fubar" are placed into the code segment
  583.     and referenced according to the code model (pc-rel or absolute).  Any
  584.     variable declared const will also be put in the code segment and
  585.     referenced similary.  However, any EXTERN'd variables referenced but
  586.     not defined in this module (i.e. defined in another module) will be
  587.     accessed using ABSOLUTE references, since you cannot make a jump table
  588.     for data variables.
  589.  
  590.     The -mS option is much more dangerous.. it works the same as -ms except
  591.     that external references use pc-relative addressing as well. your final
  592.     executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE
  593.     VIA PC-RELATIVE ADDRESSING.  If you have a choice, please use -ms
  594.     instead of -mS .
  595.  
  596.     'const __chip' variables will also be placed in the code section, but
  597.     these always use absolute references since the code section is not
  598.     combined together with other code sections.  You may also override
  599.     default access method (pc-rel/absolute) by using the __near and __far
  600.     keywords, but this is not advised.
  601.  
  602.     The -ms option affects the main compiler DC1 and can be specified
  603.     independantly for each source module (i.e. some can have it while
  604.     others do not, though normally all will have it one way or the other)
  605.  
  606.     WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to
  607.     -mS
  608.  
  609.                 RESIDENTABILITY
  610.  
  611.     Two options are available to generate residentable executables and one
  612.     option is available to genreate a non-residentable executable with no
  613.     relocation information (loads quickly).
  614.  
  615.         RES?   RELOC?   DataLim CodeLim Alloc?  Hunks
  616.  
  617.     -md     no       yes        64K(1)  none    no      DATA, CODE
  618.     -mD     no       yes        none    none    no        DATA, CODE, optionally more
  619.     -r        yes    yes        64K     none    yes     DATA, CODE
  620.     -pr     yes    no        64K     32K     yes     CODE (combined DATA+CODE)
  621.     -pi     no       no        64K     32K     no        CODE (combined DATA+CODE)
  622.  
  623.     RES:    Can this program be made resident (dlink sets Pure bit)
  624.  
  625.     RELOC:    Will this executable contain 32-bit relocations?
  626.  
  627.     DATALIM:    The maximum amount of DATA+BSS that may be declared
  628.  
  629.     CODELIM:    The maximum size of the CODE
  630.  
  631.     ALLOC:    Does the startup code allocate a run time DATA+BSS segment?
  632.         (basically, resident programs must, non-resident programs
  633.         do not)
  634.  
  635.     HUNKS:    Number and type of hunks that may exist in the executable
  636.  
  637.  
  638.     -md     default
  639.  
  640.     -mD     used when final executable contains more than 64KBytes of data
  641.  
  642.     -r        most often used option
  643.  
  644.     -pr     used instead of -r if there is only a little initialized data
  645.  
  646.         Can be used with most programs but requires one large chunk of
  647.         memory instead of the two smaller chunks that -r allocates
  648.  
  649.         Also used in ROMable applications
  650.  
  651.     -pi     used instead of default when there is only a little INITIALIZED+BSS
  652.  
  653.         Can be used with many small programs that you do not intend to
  654.         make residentable, to make them load extremely fast (since there
  655.         is no relocation information).
  656.  
  657.         Also used in ROMable applications
  658.  
  659.     The __geta4 type qualifier will NOT work with residentable programs.
  660.  
  661.     You cannot use __far when accessing non-const (see -ms option) data
  662.     in residentable programs
  663.  
  664.     USING THE -ms OPTION can drastically reduce the amount of data that
  665.     needs to be allocated/copied when a resident program starts up by
  666.     moving string constants into the code section (only the data section is
  667.     duplicated), reducing overhead in both time and space for each
  668.     invocation of the RESIDENT'd program.
  669.  
  670.     To use one of the options -r, -pi, or -pr specify on the DCC line when
  671.     both compiling and linking your code.  The resulting executable will have
  672.     the pure bit set (for -r and -pr options) and be residentable.
  673.  
  674.     -r and -pr generate no BSS since the startup code is going to allocate
  675.     the DATA+BSS space.  -pi generates BSS space in the code segment just
  676.     after the initialized data.
  677.  
  678.     default    uses c.o
  679.     -r        uses c.o
  680.     -pi     uses c_pi.o
  681.     -pr     uses c_pr.o
  682.  
  683.